#' Add a Categorical Column to Data Frame
#'
#' This function adds a new column to a data frame, mapping values from the
#' `SOURCE` column to new categories provided by the user.
#'
#' @param df A data frame containing a `SOURCE` column with original identifiers
#'   (e.g., filenames).
#' @param category A character vector of new category labels. The order of
#'   `category` must correspond to the order of unique values in `df$SOURCE`.
#' @param new_col_name A character string specifying the name of the new column
#'   to be added. Defaults to `"GROUP"`.
#'
#' @return A data frame (`df`) with the new categorical column appended.
#'
#' @export
#'
#' @examples
#' \dontrun{
#' # Example data frame
#' df = data.frame(
#'   SOURCE = rep(c("file1.xlsx", "file2.xlsx", "file3.xlsx"), each = 10),
#'   Value = rnorm(30)
#' )
#'
#' # Define new categories
#' my_categories = c("Control", "Treatment_A", "Treatment_B")
#'
#' # Add the new category column
#' df_with_group = set_category_base(df, my_categories)
#' head(df_with_group)
#' }
set_category_base = function(df, category, new_col_name = "GROUP") {
  # Input validation
  if (!"SOURCE" %in% colnames(df)) {
    stop("The input data frame `df` must contain a column named 'SOURCE'.")
  }
  
  source_unique = unique(df$SOURCE)
  
  if (length(source_unique) != length(category)) {
    stop(paste("The length of `category` (", length(category), 
               ") must match the number of unique values in `df$SOURCE` (", length(source_unique), ").", sep = ""))
  }
  
  if (!is.character(category)) {
    stop("`category` must be a character vector.")
  }
  
  # Create the new column using match()
  df[[new_col_name]] = category[match(df$SOURCE, source_unique)]
  
  return(df)
}

